package org.jplcc;

import java.util.Collection;

/**
 * Comprehensive information about the PLC as a whole.
 * <P>
 * This interface is implemented by driver vendors to let users know the
 * capabilities of a Programmable Logic Controller (PLC) in combination with the
 * driver based on JPLCC technology ("JPLCC driver") that is used with it.
 * Different PLC often support different data types. In addition, a driver may
 * implement a feature on top of what the PLC offers. Information returned by
 * methods in this interface applies to the capabilities of a particular driver
 * and a particular PLC working together.
 * <P>
 * A user for this interface is commonly a tool that needs to discover how to
 * deal with the underlying PLC. This is especially true for applications that
 * are intended to be used with more than one PLC.
 * <P>
 */
public interface PLCMetadata {

    /**
     * Retrieves the name of this PLC product.
     * 
     * @return PLC product name
     * @throws JPLCCException
     *             if a plc access error occurs
     */
    String getPLCProductName() throws JPLCCException;

    /**
     * Retrieves the name of this PLC driver.
     * 
     * @return PLC driver name
     * @throws JPLCCException
     *             if a plc access error occurs
     */
    String getDriverName() throws JPLCCException;

    /**
     * Retrieves the version number of this PLC driver as a <code>String</code>.
     * 
     * @return PLC driver version
     * @throws JPLCCException
     *             if a plc access error occurs
     */
    String getDriverVersion() throws JPLCCException;

    /**
     * Retrieves this PLC driver's major version number.
     * 
     * @return PLC driver major version
     */
    int getDriverMajorVersion();

    /**
     * Retrieves this PLC driver's minor version number.
     * 
     * @return PLC driver minor version number
     */
    int getDriverMinorVersion();

    /**
     * Retrieves the connection that produced this metadata object.
     * 
     * @return the connection that produced this metadata object
     * @exception JPLCCException
     *                if a plc access error occurs
     */
    Connection getConnection() throws JPLCCException;

    /**
     * Retreives all supported JPLCC types supported by the connection that
     * produced this metadata object.
     * 
     * @return all supported JPLCC types supported by the connection that
     *         produced this metadata object
     * @throws JPLCCException
     *             if a plc access error occurs
     */
    Collection<Type> getSupportedTypes() throws JPLCCException;
}
